home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_libgeotiff.idb / usr / freeware / share / doc / libgeotiff / manual.txt.z / manual.txt
Text File  |  2002-10-07  |  17KB  |  457 lines
  1. -------------------------------------------------------------
  2.  
  3.           Manual for Libgeotiff Library and Utilities
  4.  
  5. -------------------------------------------------------------
  6.  
  7. Documentation Author: Niles Ritter
  8. Last Modified: 31 Jul 95
  9.   
  10. See: http://www.remotesensing.org/geotiff/api/index.html 
  11.   for up to date API documentation
  12.   
  13. -------------------------------------------------------------
  14. Contents:
  15.  
  16.   1. The LibGeoTIFF library
  17.   
  18.      1.1 Preliminaries
  19.      1.2 Calling Sequences
  20.      1.3 Examples
  21.  
  22.   2. The LibGeoTIFF Utilities
  23.   
  24.      2.1 listgeo   - dump a GeoTIFF metadata file
  25.      2.2 geotifcp  - install GeoTIFF from metadata
  26.  
  27. -------------------------------------------------------------
  28. 1. The LibGeoTIFF library
  29.  
  30. -------------------------------------------------------------
  31. 1.1 Preliminaries
  32.  
  33. -------------------
  34. 1.1.1 Compliance:
  35.  
  36.     ANSI-C:  The GeoTIFF library is fully ANSI compliant and
  37.        should compile under any ANSI compiler. It is not guaranteed
  38.        to compile under K&R compilers.
  39.     
  40.     C++:   All headers have the appropriate C++ bindings permitting
  41.        the correct linkage to C++ routines.
  42.        
  43. -------------------
  44. 1.1.2 Interfaces:
  45.  
  46.     xtiffio.h: the primary interface header file for all TIFF
  47.                 routines, using the extended GeoTIFF tags.
  48.                 
  49.     geotiffio.h: the primary interface header file for all GTIF 
  50.                  routines, keys and code values.
  51.  
  52.     geotiff.h:  an interface header file for all GTIF 
  53.                  routines, if code values are not required.
  54.  
  55.     geokeys.h:   defines all valid GEOTIFF GeoKeys.
  56.     
  57. -------------------
  58. 1.1.3 Defined macros:
  59.  
  60.   All of the tag, key and key-value symbolic names in the GeoTIFF spec are
  61.   supported and defined by the inclusion of "geotiffio.h". In addition,
  62.   the following useful values are defined:
  63.   
  64.     GvCurrentVersion:  The current GeoTIFF Directory version. Should always be 1.
  65.     GvCurrentRevision: The current GeoTIFF Key Revision.
  66.     GvCurrentMinorRev: The current GeoTIFF Key-Value (minor) Revision.
  67.     
  68.     KvUndefined:      The universal Key value for "undefined" items.
  69.     KvUserDefined:    The universal Key value for "user-defined" items.
  70.  
  71.     
  72. -------------------
  73. 1.1.4 Defined Types:  
  74.  
  75.     TIFF             the type of a TIFF file descriptor (if LIBTIFF is used).
  76.     GTIF             the type of a GeoTIFF file descriptor.
  77.     GTIFPrintMethod  the type of a print method passed to GTIFPrint().
  78.     GTIFReadMethod   the type of a read method passed to GTIFImport().
  79.     geokey_t         the type of a GeoTIFF key variable.
  80.     tagtype_t        the type of a TIFF tag variable, such as TYPE_DOUBLE.
  81.  
  82.  
  83. -------------------
  84. 1.1.5 Key and Code Databases:
  85.  
  86.     All geokeys are defined and named in the database file
  87.     "geokeys.inc", which in turn is included in "geokeys.h"
  88.     and several other files. The symbolic enumerated names are identical
  89.     to those used in the Appendix of the GeoTIFF spec.
  90.     
  91.     The geokey code values are stored in the other database files
  92.     having the ".inc" suffix, which in turn are all referenced by
  93.     the file "geovalues.h". The ones with names beginning with
  94.     "epsg_" are codes registered in the EPSG/POSC tables, while
  95.     those beginning with "geo_" are specific to GeoTIFF.
  96.     
  97.  
  98. -------------------------------------------------------------
  99. 1.2 Calling Sequences
  100.  
  101. -------------------
  102. 1.2.1 TIFF-level interface
  103.  
  104.  
  105. 1.2.1.1  GTIFNew  -- Set up a new GeoTIFF file Descriptor
  106.     GTIF*     GTIFNew(void *tif);
  107.  
  108. GTIFNew() takes an existing TIFF file descriptor and creates
  109. a GTIF GeoTIFF file-I/O object for reading and writing
  110. GeoTIFF keys and values. The TIFF file must currently be open,
  111. though it may be either read or write mode.
  112.  
  113.  
  114. 1.2.1.2 GTIFFree
  115.     void      GTIFFree(GTIF *gtif);
  116.  
  117. Destroys the GeoTIFF file descriptor following reading or writing
  118. the keys.
  119.  
  120.  
  121. 1.2.1.3 GTIFWriteKeys
  122.     int       GTIFWriteKeys(GTIF *gtif);
  123.  
  124. This routine must be called for a new GeoTIFF file after all of 
  125. the desired Keys are defined and set with GTIFSetKey(). This does
  126. not explicitly write anything out to the file, but it does call
  127. the TIFF-level routines to install the TIFF tag values, which
  128. in turn are written to the file when the TIFF file descriptor
  129. is closed. A GeoTIFF file cannot be opened for updating; only
  130. pure read or write is supported.
  131.  
  132.  
  133. 1.2.1.4 GTIFFDirectoryInfo
  134.     void      GTIFFDirectoryInfo(GTIF *gtif, int *versions, int *keycount);
  135.  
  136. Returns header information about the GeoTIFF file directory. The <versions>
  137. is an array of 3 integers, giving the GeoTIFF Version, followed by
  138. the major and minor revisions. The <keycount> argument returns the number
  139. of keys currently defined in this file. 
  140.  
  141. -------------------
  142. 1.2.2 GeoKey Access 
  143.  
  144.  
  145. 1.2.2.1 GTIFKeyInfo
  146.     int       GTIFKeyInfo(GTIF *gtif, geokey_t key, int *size, tagtype_t* type);
  147.  
  148. Returns the number of values defined for key <key> if currently defined in the file, and 
  149. returns in <size> the size of individual key values, and the <type>. If the
  150. key is not defined, 0 is returned. You may pass in NULL pointers to any parameters
  151. you do not need (such as the type).
  152.  
  153.  
  154. 1.2.2.1 GTIFKeyGet
  155.     int       GTIFKeyGet(GTIF *gtif, geokey_t key, void *val, int index, int count);
  156.  
  157. Accesses the key value(s). If there are multiple values (such as ASCII), they
  158. may be accessed individually, starting at <index> and returning <count> values.
  159. The total number of values accessed is returned. Note: unline TIFFGetField() 
  160. memory is not allocated for multiple-value arrays such as ASCII. To get the
  161. length of an array call GTIFKeyInfo first, which returns the size and count
  162. of the data.  If the values are key-codes they should be declared of type
  163. "geocode_t", which is unsigned SHORT.
  164.  
  165.  
  166. 1.2.2.1 GTIFKeySet
  167.     int       GTIFKeySet(GTIF *gtif, geokey_t keyID, tagtype_t type, int count,...);
  168.  
  169. Defines and sets the specified key values. Note that this does not install the
  170. tag-level information in the file; to do that you must call GTIFWriteKeys().
  171. For single-valued non-ASCII keys (which are most of them), you must pass the
  172. values in by value not reference. You must use the correct type for the
  173. values: doubles for floating point, strings for ASCII, and "geocode_t" for
  174. SHORT codes (the symbolic names may be used in most cases).
  175.  
  176.  
  177. 1.2.3 Metadata Import-Export utilities 
  178.  
  179.     void      GTIFPrint(GTIF *gtif, GTIFPrintMethod print, void *fd);
  180.     int       GTIFImport(GTIF *gtif, GTIFReadMethod scan, void *fd);
  181.     
  182.     char*     GTIFKeyName(geokey_t key);
  183.     char*     GTIFValueName(geokey_t key,int value);
  184.     char*     GTIFTypeName(tagtype_t type);
  185.     char*     GTIFTagName(int tag);
  186.     int       GTIFKeyCode(char * key);
  187.     int       GTIFValueCode(geokey_t key,char *value);
  188.     int       GTIFTypeCode(char *type);
  189.     int       GTIFTagCode(char *tag);
  190.  
  191. The GTIFPrint() routine dumps a GeoTIFF metadata stream out to
  192. a specified file <fd>, either for human interpretation or for
  193. input to another program. If <fd> is NULL the data is written
  194. to the standard output.  
  195.  
  196. The GTIFImport() routine performs the inverse; given a metadata file
  197. specified by <fd> (or stdin if <fd> is NULL) install the corresponding
  198. tags and keys into the current GeoTIFF file. Note that the 
  199. import routine only calls GTIFKeySet(), and so it is up to the
  200. client program to call GTIFWriteKey() in order to explicitly
  201. write the keys out to the file.
  202.  
  203. The GTIFxxxName() routines all take a numeric code, key or tag and
  204. return a pointer to a static string name associated with the value.
  205. In the case of Key-Values, the key must be explicitly defined in
  206. order to establish the scope of the name-search. A string is always
  207. returned; however, if the code is not recognized the string is
  208. of the format "Unknown-%d", where %d is the input code value.
  209.  
  210. The GTIFxxxCode() routines perform the reverse operation; given
  211. an ASCII string name it tries to find the corresponding code,
  212. key or tag numerical value, in a case-sensitive manner. If the
  213. string is not recognized the value -1 is return (no valid codes
  214. are negative). For consistency, any strings of the form "Unknown-%d"
  215. where %d is a decimal integer will return the specified integer. 
  216.  
  217. Note: be careful when assigning variables to GTIFxxxCode; for example,
  218. the geokey_t type is unsigned, and so if -1 is returned, this will
  219. result in a value of 65535. To be safe, always use signed integers
  220. for the assignment, and pass them on to an unsigned type after
  221. checking that the value is positive.
  222.  
  223.  
  224. -------------------------------------------------------------
  225. 1.3 Examples
  226.  
  227.  
  228. A typical use of LIBGEOTIFF for creating a GeoTIFF file is
  229.  
  230.     #include "xtiffio.h"  /* for TIFF */
  231.     #include "geotiffio.h" /* for GeoTIFF */
  232.     void main()
  233.     {
  234.         TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
  235.         GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
  236.         
  237.         /* Open TIFF descriptor to write GeoTIFF tags */
  238.         tif=XTIFFOpen(fname,"w");  
  239.         if (!tif) goto failure;
  240.         
  241.         /* Open GTIF Key parser */
  242.         gtif = GTIFNew(tif);
  243.         if (!gtif) goto failure;
  244.         
  245.         /* Set up standar TIFF file */
  246.         TIFFSetField(tif,TIFFTAG_IMAGEWIDTH,    WIDTH);
  247.         /* set other TIFF tags and write out image ... */
  248.                 
  249.         /* Set GeoTIFF information */
  250.         GTIFKeySet(gtif, GTModelTypeGeoKey, TYPE_SHORT, 1, ModelGeographic);
  251.         /* set other GeoTIFF keys ... */
  252.         
  253.         /* Store the keys into the TIFF Tags */
  254.         GTIFWriteKeys(gtif);
  255.         
  256.         /* get rid of the key parser */
  257.         GTIFFree(gtif);
  258.         
  259.         /* save and close the TIFF file descriptor */
  260.         XTIFFClose(tif);
  261.         
  262.         exit (0);
  263.     failure:
  264.         exit (-1);
  265.     }
  266.  
  267. While a typical use of the code for reading tags is:
  268.  
  269.     #include "xtiffio.h"  /* for TIFF */
  270.     #include "geotiffio.h" /* for GeoTIFF */
  271.     enum {VERSION=0,MAJOR,MINOR};
  272.     void main()
  273.     {
  274.         TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
  275.         GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
  276.         int versions[3];
  277.         int cit_length;
  278.         geocode_t model;    /* all key-codes are of this type */
  279.         char *citation;
  280.         
  281.         /* Open TIFF descriptor to read GeoTIFF tags */
  282.         tif=XTIFFOpen(fname,"r");  
  283.         if (!tif) goto failure;
  284.         
  285.         /* Open GTIF Key parser; keys will be read at this time. */
  286.         gtif = GTIFNew(tif);
  287.         if (!gtif) goto failure;
  288.  
  289.         /* Get the GeoTIFF directory info */
  290.         GTIFFDirectoryInfo(gtif,versions,0);
  291.         if (versions[MAJOR] > 1)
  292.         {
  293.             printf("this file is too new for me\n"); goto failure;
  294.         }
  295.         if (!GTIFKeyGet(gtif, GTModelTypeGeoKey, &model, 0, 1))
  296.         {
  297.             printf("Yikes! no Model Type\n") goto failure;
  298.         }
  299.         
  300.         /* ASCII keys are variable-length; compute size */
  301.         cit_length = GTIFKeyInfo(gtif,GTCitationGeoKey,&size,&type);
  302.         if (cit_length > 0)
  303.         {
  304.             citation = malloc(size*cit_length);
  305.             if (!citation) goto failure;
  306.             GTIFKeyGet(gtif, GTCitationGeoKey, citation, 0, cit_length);
  307.             printf("Citation:%s\n",citation);
  308.         }
  309.  
  310.         /* Get some TIFF info on this image */
  311.         TIFFGetField(tif,TIFFTAG_IMAGEWIDTH,    &width);
  312.         
  313.         /* get rid of the key parser */
  314.         GTIFFree(gtif);
  315.         
  316.         /* close the TIFF file descriptor */
  317.         XTIFFClose(tif);
  318.         
  319.         exit (0);
  320.     failure:
  321.         exit (-1);
  322.     }
  323.  
  324.  
  325.  
  326. -------------------------------------------------------------
  327. 2. The LibGeoTIFF Utilities
  328.  
  329. -------------------------------------------------------------
  330. 2.1 listgeo   - dump a GeoTIFF metadata file
  331.  
  332. Syntax:   listgeo [-tfw] [-no_norm] [-t tabledir] inputfile
  333.  
  334. The program listgeo takes a GeoTIFF file as input and dumps to
  335. the standard output a GeoTIFF "metadata" file, which is human
  336. readable, and may also be used as input to other programs which
  337. use the "GTIFImport" routine, such as geotifcp, below.
  338.  
  339. The -tfw flag may be passed to force generation of an ESRI style .tfw
  340. file as well as the metadata file.  
  341.  
  342. The -no_norm flag will supress reporting of normalized parameters, and
  343. reporting of corner points. 
  344.  
  345. The "-t tabledir" flag overrides the programs concept of how to file the
  346. EPSG CSV files, causing it to look in directory "tabledir". 
  347.  
  348. ------------------------
  349. GeoTIFF Metadata Format:
  350.  
  351. For the formalist junkies, we will define a GeoTIFF metadata format
  352. in an unambiguous fashion, and follow that by a concrete example.
  353.  
  354. The metadata format is defined as follows (all strings not placed
  355. between <braces> are string literals, case-sensitive, and any entry
  356. followed by "*" or "*<number>" indicates multiple entries):
  357.  
  358. <Geotiff_Metadata> = <Geotiff_Header> + <GeoTIFF_Body> + <GeoTIFF_Trailer>
  359.  
  360.    <Geotiff_Header> = <White_Space> + Geotiff_Information: + <Return>
  361.    <GeoTIFF_Trailer> = <White_Space> + End_Of_Geotiff. + <Return>
  362.    <GeoTIFF_Body> = <GeoTIFF_Info> + <GeoTIFF_Tags> + <GeoTIFF_Keys>
  363.       <GeoTIFF_Info> = <GeoTIFF_Version> + <GeoTIFF_Revision>
  364.          <GeoTIFF_Version> = Version: + <Single_Space> + <Version> + <Return>
  365.             <Version> = <Integer>
  366.          <GeoTIFF_Revision> = Revision: + 
  367.                <Single_Space> + <Major_Rev> + <Period> + <Minor_Rev> + <Return>
  368.                <Major_Rev> = <Integer>
  369.                <Minor_Rev> = <Integer>
  370.       <GeoTIFF_Tags> =  <Tag_Header> + <Tag_Entry>* + <Tag_Trailer>
  371.          <Tag_Header> = <White_Space> + Tagged_Information: + <Return>
  372.          <Tag_Trailer> = <White_Space> + End_Of_Tags. + <Return>
  373.          <Tag_Entry> = <Tag_Entry_Header> + <Tag_Entry_Row>*
  374.             <Tag_Entry_Header> = <White_Space> + 
  375.                      <Tag_Name> + <Tag_Dimension> + <Colon> + <Return>
  376.                <Tag_Dimension>  = "(" + <NRows> + <Comma> + <NCols> + ")"
  377.                    <NRows> = <Integer>
  378.                    <NCols> = <Integer>
  379.             <Tag_Entry_Row> = <White_Space> + <Double_Float>*<NCols> + <Return>
  380.       <GeoTIFF_Keys> =  <Key_Header> + <Key_Entry>* + <Key_Trailer>
  381.          <Key_Header> = <White_Space> + Keyed_Information: + <Return>
  382.          <Key_Trailer> = <White_Space> + End_Of_Keys. + <Return>
  383.          <Key_Entry> = <Key_Entry_Header> + <Key_Entry_Value>
  384.             <Key_Entry_Header> = <White_Space> + 
  385.                      <Key_Name> + <Key_Dimension> + <Colon> + <Return>
  386.               <Key_Dimension> = "(" + <Key_Format> + <Comma> + <Key_Count> + ")"
  387.             <Key_Entry_Value> = (<Key_Value> | <Numeric_Value> | <Ascii_Value>)
  388.                <Numeric_Value> = (<Integer> | <Double_Float>)
  389.                <Ascii_Value> = <Double_Quote> + <String> + <Double_Quote>
  390.  
  391.    <Tag_Name> = All symbolic tag names defined in GeoTIFF spec.
  392.    <Key_Name> = All symbolic key names defined in GeoTIFF spec.
  393.    <Key_Value> = All symbolic value names defined in GeoTIFF spec.
  394.    <Key_Format> = (Short | Ascii | Double)
  395.    
  396. And for the pedantic:
  397.    <White_Space> = (<Single_Space> | <Tab>)*
  398.    <Double_Float> = <Mantissa><Exponent>
  399.    <Mantissa> = <Sign><Integer><Period><Integer>
  400.    <Exponent> = ( |e<Sign><Integer>)
  401.    <Sign> = ( |+|-)
  402.    <Integer> = (0|1|2|3|4|5|6|7|8|9)*
  403.    ...
  404.  
  405.  
  406. Example (default output of listgeo):
  407.  
  408. Geotiff_Information:
  409.    Version: 1
  410.    Key_Revision: 0.2
  411.    Tagged_Information:
  412.       ModelTiepointTag (2,3):
  413.          0                  0                  0
  414.        130                 32                  0
  415.       ModelPixelScaleTag (1,3):
  416.          1                  1                  0
  417.       End_Of_Tags.
  418.    Keyed_Information:
  419.       GTModelTypeGeoKey (Short,1): ModelTypeGeographic
  420.       GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
  421.       GTCitationGeoKey (Ascii,16): "Just An Example"
  422.       GeographicTypeGeoKey (Short,1): User-Defined
  423.       GeogCitationGeoKey (Ascii,24): "Everest Ellipsoid Used."
  424.       GeogGeodeticDatumGeoKey (Short,1): User-Defined
  425.       GeogLinearUnitsGeoKey (Short,1): Linear_Meter
  426.       GeogAngularUnitsGeoKey (Short,1): Angular_Degree
  427.       GeogEllipsoidGeoKey (Short,1): Ellipse_Everest_1830_1967_Definition
  428.       GeogSemiMajorAxisGeoKey (Double,1): 6377298.556
  429.       GeogInvFlatteningGeoKey (Double,1): 300.8017
  430.       End_Of_Keys.
  431.    End_Of_Geotiff.
  432.    
  433.    
  434. -------------------------------------------------------------
  435. 2.2 geotifcp  - Copy a TIFF file and install GeoTIFF info from metadata.
  436.  
  437. Syntax:   geotifcp [options] [-e esri_worldfile] [-g metadata] input output
  438.  
  439. The program geotifcp is identical in function to the LIBTIFF program
  440. "tiffcp", with the additional feature that if the "-g <metadata>"
  441. option is used the GeoTIFF information from the file <metadata> 
  442. will be installed into the output file.  The "-e worldfile" option will 
  443. override the tiepoint and scale information from the metadata file based
  444. on the contents of the ESRI worldfile. 
  445.  
  446. If the "-g" option is not used, the opposite effect occurs: all 
  447. GeoTIFF information is filtered out of the input file before being
  448. written to the new output file.
  449.  
  450. "geotifcp" inherits all the other file-transformation capabilities
  451. of the tiffcp program; for help on the additional parameters give
  452. the command:
  453.  
  454.   %  geotifcp -h
  455.  
  456. -------------------------------------------------------------
  457.